Crate fmmap

source ·
Expand description

fmmap

A flexible and convenient high-level mmap for zero-copy file I/O.

English | 简体中文

github Build codecov

docs.rs crates.io rustc

license-apache license-mit

Design

The design of this crate is inspired by Dgraph’s mmap file implementation in Stretto.

All of file-backed memory map has the potential for Undefined Behavior (UB) if the underlying file is subsequently modified (e.g. the file is deleted by another process), in or out of process, this crate tries to avoid this situation by provide file lock APIs.

This crate supports std and popular async runtime(tokio, async-std, smol), and thanks to macro in Rust, it is super easy to support any new async runtime. For details, please see the implementation for tokio, async-std, smol of the source code.

Features

  • dozens of file I/O util functions
  • file-backed memory maps
  • synchronous and asynchronous flushing
  • copy-on-write memory maps
  • read-only memory maps
  • stack support (MAP_STACK on unix)
  • executable memory maps
  • file locks.
  • tokio
  • smol
  • async-std

Installation

  • std
[dependencies]
fmmap = 0.2

[dependencies]
fmmap = { version = "0.2", features = ["tokio-async"] }

[dependencies]
fmmap = { version = "0.2", features = ["std-async"] }

[dependencies]
fmmap = { version = "0.2", features = ["smol-async"] }

Examples

This crate is 100% documented, see documents for examples.

TODO

  • add benchmarks
License
Licensed under either of Apache License, Version 2.0 or MIT license at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Modules

  • async_stdasync-std and async-trait
    async_std based mmap file
  • error
    Errors in this crate
  • raw
    Components of mmap file.
  • syncsync
    std based mmap file
  • tokiotokio and async-trait
    tokio based mmap file
  • utils
    File I/O utils function

Macros

Structs

  • MetaData
    Metadata information about a file. This structure is returned from the metadata or symlink_metadata function or method and represents known metadata about a file such as its permissions, size, modification times, etc
  • MmapFilesync
    A read-only memory map file.
  • MmapFileMutsync
    A writable memory map file.
  • MmapFileReadersync
    MmapFileReader helps read data from mmap file like a normal file.
  • MmapFileWritersync
    MmapFileWriter helps read or write data from mmap file like a normal file.
  • Optionssync
    A memory map builder, providing advanced options and flags for specifying memory map file behavior.

Traits